|
 |
 |
::
|
|
|
TSampleDisplay3D Component
A component for use in Win32 (9x/ME/2K/XP/Vista/W7) and Win64 software with BASS.
It's purpose is to provide the most powerful and efficient (yet easy to use), 3D sample functions like displaying the sample in 3D with configurable colors,
automatic support for ID3v2 SESC, making a selection, zooming, quick-playing from click, configurable selection playback repeat count, edit and
create Subsong seekpoints, etc. all on a powerfull Direct3D display.
There are two ways to use this component.
TSampleDisplay3D for Delphi and Sample Display 3D Library for any developer environment that supports the stdcall calling convention.
The most you get is from the Delphi version, you can access all the underlying stuff, and the least you get is the standalone .dll version but can use in any developer environment.
All of these components are refered to as TSampleDisplay3D.
You should also see the included example program Tutorial1's source-code for example of how to use TSampleDisplay3D in your own programs.
If you are looking for a more precise and scientific audio display component, take a look at TGraphDisplay3D.
If you are looking for a simple sample display creator component that just returns a HBitmap handle with a picture, take a look at Sample Display Library.
Requirements
TSampleDisplay3D in shareware and commercial software?
The component is free for free software. If like it and use it for shareware and commercial software you have to buy a license.
Installation
- In Delphi menu: File/New/Package Delphi
- Unpack the BASS package (bassxx.zip). bass.dll and Delphi/bass.pas is needed in the search path.
- Unpack the ClootieDX9 folder, all the files inside are needed in the search path.
- ID3v1Library.pas and ID3v2Library.pas is needed in the search path.
- Put bass.dll and d3dx9ab.dll in Delphi's \bin folder.
- In project manager (in the upper-right corner by default), right-click on "Package1.dproj" and select "Add..."
- Unit file name: click "Browse" and select "SampleDisplay3D.pas" and click "Ok"
- In project manager (in the upper-right corner by default), right-click on "Package1.dproj" and select "Install..."
- Save the package.
If everything went smooth, you can access the TSampleDisplay3D component on 3delite's tab.
Supported audio file formats: MP3, MP2, MP1, OGG, WAV and music modules. Yes, it
supports music modules too! :, MO3, IT, XM, S3M, MTM, MOD, UMX
If you want your application to handle many more audio file formats, like: Flac, OptimFrog, WavPack, Monkey's Audio, Musepack, TTA, ALAC (Apple Lossless), AC3, Speex, AACH, AAC/MP4 and AC3, etc. (you can also use winamp input plugins trough a BASS plugin) check the great BASS add-ons on the BASS page.
NOTE: To run the EXEs, first you'll have to copy bass.dll and d3dx9ab.dll into the same directory as the EXEs.
The Tutorial presentation demo in action:
Properties
- ActiveIndex: Specifies which stream is displayed on the 3D panel.
- AllowSelect: Turn on/off selection possibility.
- AllowQuickPlay: Turn on/off middle-mouse button quick play and space-bar play/pause
possibility.
- AllowWhhelZoom: Turn on/off mouse-wheel zoom in/out possibility.
- AutoReInit: If set to True Direct3D is re-initialized every time when the panel
is resized. Very slow, but gives always precise 1:1 resolution.
- BaseStreamCount: Specifies how much slots are avalable for streams. Default is 1.
If you need more slots set to a greater value.
Note: It is not recommended to increment this value in single steps (causes
memory fragmentation), set it to a given value only when you know how much
slots you'll need. You can leave it at 1 if you don't want to use the slots
feature at all, and you want to use only a single slot.
- CacheSampleInSeparateThread: Specifies weather to run the sample caching in separate thread. True by default.
- D3DVertexProcessingMode: Older 3D gfx card don't have hardware vertex processing, then select sofware mode.
vpHardware: Hardware Vertex Processing
vpMixed: Mixed Vertex Processing
vpSoftware: Software Vertex Processing
- Panel3DColor: Specifies the background color for the 3D panel when no 3D graphic is
drawn.
- Panel3DPicture: Specifies the picture used when no 3D graphic is drawn.
- SampleAmplitude: Specifies the sample graphics amplitude on the 3D display.
- SampleAnim: If set to True the 3D sample is animated. Setting to False will speed
up the inital show, the Zoom and ShowAll functions.
- SampleDownColor: Sample's bottom color (Left and right channel respectively).
- SampleFFT: If set to True FFT graphic is drawn below the sample when the stream
channel is playing.
- SampleLines: Draw the sample graphics as lines not as triangles (slower).
- SampleResolution: Max. triangle/line count for the sample's object. Default is 300000.
You may need to lower this to 100000 or even 50000 on some graphic cards.
The bigger the resolution the slower the rendering but the sample graphics is
more detailed.
Modern graphics cards can display about half a million triangles in one go.
- SampleScroll: If set to True the 3D sample is scrolled with the playing position.
- SampleUpColor: Sample's top color (Left and right channel respectively).
- ScrollBarHeight: Specifies the scroll bar's height.
- SelectionRepeatCount: Specifies how many times to repeat playing the selection.
- SelectionRewind: Specifies weather to position playing position to selection start
or to leave where it stoped (at the selection end).
- ShowSubsongs: If set to True Subsongs are shown.
- SuppressErrors: Do not display any error dialogs.
- UpdateSelectionPlayOnMove: When playing selection and making selection in the same
time, "selection end" BASS sync position will be updated accordingly. The
playing will jump back (or stop) from the new selected position.
- WriteSESC: Save sample cache (MP3 Stream Editor format) in ID3v2 SESC frame.
Advised as it only increases file size only a few 10KBs but results nearly
instant displaying of audio files.
If set to True, after every CacheSample() if the audio file has an ID3v2 Tag
the SESC will be saved, if it doesnt have ID3v2 Tag then it won't be. If you
want to force saving the SESC, regardless if the audio file has an ID3v2 or
not use the ID3v2_SetSESC() function with the Force flag set to True.
Note: ID3v2 SESC is automatically used when opening audio files. The
OnNeedSESC event is reaised before though.
- WriteSubsongs: .cue and Helium ID3v2 Subtracks info is automatically converted and
saved as MP3 Stream Editor Subsong layout in ID3v2 frames.
You can save the Subsongs any time with the function .ID3v2_SaveSubsongs().
Events
- AfterD3DRender: is called when the sample and all the graphics had been drawn on
the surface. You can draw on the surface that will be on top of the sample
graphics.
- AfterTagSave: is called when the ID3v2 Tag is saved (eg. MP3SE Subsong layout).
- BeforeD3DRender: is called when the D3D surface is cleared and ready for drawing.
You can draw on the surface with
.Streams.Index[Index].g_pd3dDevice
that will be behind the sample graphics.
- BeforeTagSave: is called when the component is about to save the ID3v2 (eg. MP3SE
Subsong layout).
- OnD3DDestroy: is called before freeing the Direct3D object.
- OnNeedBASSChannelHandle: is called when the component needs a BASS channel handle
for playback.
Index specifies the slot needing the handle.
Flags specifies BASS_StreamCreateFile() flags needed.
If the given stream's channel handle is 0 the component tries to create a
BASS channel handle on it's own using the default BASS_StreamCreateFile()
function. If .Streams.Index[Index].Channel is not 0 then that channel
handle is used for playback.
- OnNeedBASSDecodeChannelHandle: is called when the component needs a decoding BASS
channel handle for getting the sample cache. This event will not be raised
if the .SampleCache is filled in .OnNeedSESC!
Index specifies the slot needing the handle.
A decode channel handle is needed in Channel. If Channel is 0 the component
will try to create a decoding channel on it's own using the default
BASS_StreamCreateFile() function.
- OnNeedSESC: is called when the component needs sample cache in
.Stream.Index[Index].SampleCache
You can fill it here, or if .SampleCache size is 0 on return, the component
will try to:
1.Load ID3v2 SESC cache
if not successfull:
2.Create a decode channel handle and will get the sample cache from there.
- OnSelection: is called when the user changes the selection on the sample display.
- OnSampleCachingThreadFinished: is called when the sampling caching thread has finished thus the stream is opened and ready.
Only called when CacheSampleInSeparateThread is True.
- OnSubsongChange: is called when the user is above a Subsongs seekpoint or is dragging
the Subsong seekpoint on the sample display.
Index specifies the slot where the drag occured.
SubsongNo specifies the Subsongs seekpoint that is being dragged.
Other available properties
- g_pD3D: The Direct3D Object.
- Streams.Index[Index].g_pd3dDevice: The Direct3D device for slot specified by "Index".
- FPS: Current frames per second for the Direct3D display.
- Streams[]: The slots for the audio files.
- Cancel: Set to True if you want to abort the current task (eg cache sample task).
- CancelThreadSampleCaching: Call this to cancel the sample caching when CacheSampleInSeparateThread is True.
It is automatically called if you open a new file while the sample caching is in progress.
- Progress: Current task's progress in percentage.
Functions and procedures
- StreamOpen(FileName: String; Index: Cardinal): Boolean;
Open an audio file in slot "Index".
Result is True if successfull.
- StreamClose(Index: Cardinal);
Close audio file in slot specified by "Index".
- InitD3D(Index: Cardinal): Boolean;
Initialize and display stream in slot "Index".
Result is True if successfull.
- Render;
Draw the frame. The slot specified with .ActiveIndex is drawed.
This should be called about every 30th msec (or more often) if you want smooth 3D graphics.
Another good idea is to call it in OnIdle().
- Zoom;
Zoom to the selection. The slot specified with .ActiveIndex is zoomed.
Is animated if .SampleAnim is True.
- ShowAll;
Display the whole sample. The slot specified with .ActiveIndex is showed all.
Is animated if .SampleAnim is True.
- PlaySelection;
Play the selection.
BASS channel will be created if non existent, so OnNeedBASSChannelHandle()
will be called.
The playing will rewind as specified by .SelectionRepeatCount and
.SelectionRewind.
- PlayStream(Index: Cardinal; StartPos: Int64; EndPos: Int64; FadeIn: Boolean): Boolean;
Play the slot specified by Index.
Startpos: Start position in bytes on a BASS channel handle.
EndPos: End position in bytes on a BASS channel handle.
FadeIn: Fade in when starting playback in one seconds.
BASS channel will be created if non existent, so OnNeedBASSChannelHandle()
will be called.
Result is True if successfull.
- SampleDataCache(Index: Cardinal; Force: Boolean);
Refresh (load or get) sample cache for the slot. If Force is not True
TSampleDisplay3D will first try to load ID3v2 SESC. If Force is set to True,
a new decoding channel will be created and the new sample cache will be saved
into the ID3v2 Tag if .WriteSESC is set to True.
- ID3v2_SetSESC(Index: Cardinal; Force: Boolean): Boolean;
Save sample cahce in MP3 Sream Editor format into ID3v2 SESC frame.
Force: Normally SESC will be saved only into audio files which have ID3v2 Tag. If you specify Force = True
then an ID3v2 tag will be created if non existent.
Result is True if successfull.
- StreamSaveWAV(Index: Cardinal; OutFileName: String; StartPos, EndPos: Int64): Boolean;
Save WAV PCM file from slot "Index".
OutFileName specifies where to save the file.
StartPos specifies the starting position in bytes on a BASS channel handle.
EndPos specifies the ending position in bytes on a BASS channel handle.
A decoding channel will be created, so .OnNeedBASSDecodeChannelHandle will be called also.
- StreamSaveWAV32(Index: Cardinal; OutFileName: String; StartPos, EndPos: Int64): Boolean;
Save WAV PCM file in 32bits from slot "Index".
OutFileName specifies where to save the file.
StartPos specifies the starting position in bytes on a BASS_SAMPLE_FLOAT BASS channel handle.
EndPos specifies the ending position in bytes on a BASS_SAMPLE_FLOAT BASS channel handle.
A decoding channel will be created, so .OnNeedBASSDecodeChannelHandle will be called also.
- StreamLoadCUE(Index: Cardinal; var Titles, Artists, Seeks, Albums: TStrings): String;
Manually load a .cue sheet file for the slot specified by Index.
Titles, Artists, Seeks, Albums are available as
.Streams.Index[Index].Subsongs.Titles .Streams.Index[Index].Subsongs.Artists etc.
Return value is album name.
Note: Will try to open file with the same name as the audio file but with .cue extension!
- StreamLoadSubtracks(FileName: String; var Tag: Tid3v2Tag; var Subsongs: TSubsongSeeks): Boolean;
Manually load Helium ID3v2 Subtracks for the slot specified by Index.
Tag is the ID3v2 Tag for the slot:
.Streams.Index[Index].ID3v2Tag
Subsongs:
.Streams.Index[Index].Subsongs
Result is True if succesfull.
- StreamLoadSubsongs(Index: Cardinal): Boolean;
Manually load MP3 Stream Editor ID3v2 Subsongs for the slot specified by Index.
Result is True if succesfull.
- ID3v2_SaveSubsongs(Index: Cardinal; var Tag: Tid3v2Tag; Titles, Artists, Seeks, Albums: TStrings): Boolean;
Save Subsong layout in MP3 Stream Editor ID3v2 Subsong layout format.
.Streams.Index[Index].ID3v2Tag
Titles, Artists, Seeks, Albums is available with:
.Streams.Index[Index].Subsongs.Titles etc.
Result is True if succesfull.
Other helper functions available
- BGR2RGB(BGRValue: Cardinal): Cardinal;
Convert BGR color value to RGB color value.
- Bytes2MB(Bytes: Single): String;
Convert bytes count into a readable string.
- mSec2Time(mSec: Int64): String;
Convert msec length into a readable time format.
- NGetFileSize(FileName: String): Int64;
Gives file size in bytes.
- DecodeUnicode(UnicodeString: String): String;
Decode unicode string to normal string.
Known bugs and issues
- My application using TSampleDisplay3D uses too much CPU power
- Reduce the SampleResolution (in object inspector or by code) to 5000 (minimally recommended - else should be around 300 000)
- Call Render() less - Setting the timer to 100ms should be still enough for smooth graphics
- Do not use Antialiasing
Credits
Copyright, Disclaimer, and all that other jazz
The TSampleDisplay3D is free for free software. If like it and use it in a shareware or commercial software then you have to buy a license.
This software is provided "as is", without warranty of ANY KIND, either expressed or implied, including but not limited to the
implied warranties of merchantability and/or fitness for a particular purpose. The author shall NOT be held liable for
ANY damage to you, your computer, or to anyone or anything else, that may result from its use, or misuse. Basically, you use it
at YOUR OWN RISK.
Usage of TSampleDisplay3D indicates that you agree to the above conditions.
You may freely distribute the TSampleDisplay3D package as long as NO FEE is charged and all the files remain INTACT AND UNMODIFIED.
All trademarks and other registered names contained in the TSampleDisplay3D package are the property of their respective owners.
Bug reports, Suggestions, Comments, Enquiries, etc...
If you have any of the aforementioned please email: 3delite@3delite.hu
|
|
|
|
|
|
